From 0974aa784ac6b5d327f99cae36bf8bfc67b54c4c Mon Sep 17 00:00:00 2001
From: hpk <none@none>
Date: Tue, 23 Sep 2008 12:41:22 +0200
Subject: [PATCH] [svn r58375] some updates on the filesystem front

--HG--
branch : trunk
---
 py/doc/draft_pyfs | 79 +++++++++++++++++++++++++++++++++++++++++++++++
 py/doc/future.txt | 16 +++++++++-
 2 files changed, 94 insertions(+), 1 deletion(-)
 create mode 100644 py/doc/draft_pyfs

diff --git a/py/doc/draft_pyfs b/py/doc/draft_pyfs
new file mode 100644
index 000000000..68d6944fe
--- /dev/null
+++ b/py/doc/draft_pyfs
@@ -0,0 +1,79 @@
+
+Let's do a walk through a memory filesystem. 
+
+.. >>> import py
+
+
+working with directories
+---------------------------------
+
+Let's create some directories and list them from memory::
+
+>>> fs = py.fs.MemoryFS()
+>>> fs.mkdir("x")
+>>> fs.mkdir("y")
+>>> fs.listdir()
+['x', 'y']
+
+
+Creating, removing and reading files
+---------------------------------------------
+
+>>> f = fs.open('x/file', 'w')
+>>> f.write("hello world")
+>>> f.close()
+>>> fs.listdir("x")
+['file']
+>>> f = fs.open("x/file", 'r')
+>>> f.readlines()
+['hello world']
+>>> f.seek(6)
+>>> f.read(3)
+"wor"
+>>> f.read()
+"ld"
+>>> f.close()
+>>> fs.remove("y")
+>>> fs.listdir()
+['x']
+>>> fs.remove("non-existent")
+py.error.ENOENT 
+
+stat / checking for meta information 
+---------------------------------------
+
+>>> stat = memory.stat("x")
+>>> stat.isdir()
+True
+>>> stat.isfile()
+False
+>>> stat.exists()
+True
+>>> stat.islink()
+False
+
+Linking to other objects 
+--------------------------------------------------------
+
+First an example how to link internally, i.e. within the 
+filesystem. 
+
+>>> fs.link("newitem", "x")
+>>> fs.stat("newitem").islink()
+True
+>>> fs.stat("newitem").isfile()
+True
+>>> fs.remove("newitem")  # only deletes the link itself
+>>> fs.stat("x").exists()
+
+cross-filesystem references 
+---------------------------------
+
+>>> otherfs = py.fs.MemoryFS()
+
+XXX 
+
+>>> fs.setproxy("newitem", otherfs, "otheritem")
+>>> fs.stat("newitem").exists()
+False
+>>> otherfs.mkdir("otheritem")
diff --git a/py/doc/future.txt b/py/doc/future.txt
index 0993406e0..84356a192 100644
--- a/py/doc/future.txt
+++ b/py/doc/future.txt
@@ -90,7 +90,7 @@ decreased considerably.
 Refactor path implementations to use a Filesystem Abstraction 
 ============================================================= 
 
-It seems like a good idea to refactor all python implementations to
+It seems like a good idea to refactor all `py.path`_ Path implementations to
 use an internal Filesystem abstraction.  The current code base
 would be transformed to have Filesystem implementations for e.g. 
 local, subversion and subversion "working copy" filesystems. Today 
@@ -110,6 +110,20 @@ even become interesting to think about interfacing to
 `reiserfs v4 features`_ at the Filesystem level but that
 is a can of subsequent worms).  
 
+Also interesting to check out is Will McGugan's work on 
+his `fs package`_.  
+
+I think the main question is what the very fundamental 
+filesystem API should look like.  Here are some doctests
+on how a `draft py.fs`_ could look like.  There also 
+is Matthew Scotts `dictproxy patch`_ which adds 
+``py.path.dict`` and ``py.path.proxy``. 
+
+
+.. _`dictproxy patch`: http://codespeak.net/pipermail/py-dev/attachments/20050128/d9595512/virtual1-0001.bin
+.. _`draft py.fs`: draft_pyfs
+.. _`py.path`: http://codespeak.net/py/dist/path.html
+.. _`fs package`: http://www.willmcgugan.com/2008/09/21/announcing-fs-010-a-python-file-system/#comment-60276
 .. _`memoryfs`: http://codespeak.net/svn/user/arigo/hack/pyfuse/memoryfs.py
 .. _`dictfs`: http://codespeak.net/pipermail/py-dev/2005-January/000191.html 
 .. _`pylufs`: http://codespeak.net/svn/user/arigo/hack/pylufs/