From 06f917380c8add2ebe38c2c988e3dd197d3fcb78 Mon Sep 17 00:00:00 2001 From: willmcgugan Date: Sun, 6 Mar 2011 16:46:50 +0000 Subject: More docs git-svn-id: http://pyfilesystem.googlecode.com/svn/trunk@641 67cdc799-7952-0410-af00-57a81ceafa0f --- docs/implementersguide.rst | 30 ++++++++++++++++++++++++++++++ docs/index.rst | 1 + docs/interface.rst | 8 +++++++- 3 files changed, 38 insertions(+), 1 deletion(-) create mode 100644 docs/implementersguide.rst (limited to 'docs') diff --git a/docs/implementersguide.rst b/docs/implementersguide.rst new file mode 100644 index 0000000..aa20f9d --- /dev/null +++ b/docs/implementersguide.rst @@ -0,0 +1,30 @@ +A Guide For Filesystem Implementers +=================================== + +PyFilesystems objects are designed to be as generic as possible and still expose as much functionality as possible. +With a little care, you can write a wrapper for your filesystem that allows it to work interchangeably with any of the built-in FS classes and tools. + +To create a working PyFilesystem interface, derive a class from :py:class:`fs.base.FS` and implement the 9 :ref:`essential-methods`. + + +Filesystem Errors +----------------- + +With the exception of the constuctor, FS methods should throw :class:`fs.errors.FSError` exceptions in preference to any specific exception classes, +so that generic exception handling can be written. +The constructor *may* throw a non-FSError exception, if no appropriate FSError exists. +The rational for this is that creating an FS interface may require specific knowledge, +but this shouldn't prevent it from working with more generic code. + +If specific exceptions need to be translated in to an equivalent FSError, +pass the original exception class to the FSError constructor with the 'details' keyword argument. + +For example, the following translates some ficticious exception in to an FS exception, +and passes the original exception as an argument.:: + + try: + someapi.open(path, mode) + except someapi.UnableToOpen, e: + raise errors.ResourceNotFoundError(path=path, details=e) + +Any code written to catch the generic error, can also retrieve the original exception if it contains additional information. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index b415571..241c58a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,6 +24,7 @@ Guide expose.rst utilities.rst commands.rst + implementersguide.rst Code Documentation ------------------ diff --git a/docs/interface.rst b/docs/interface.rst index bf3ae9a..f39ed65 100644 --- a/docs/interface.rst +++ b/docs/interface.rst @@ -9,6 +9,8 @@ It may also be worthwhile implementing some of the non-essential methods, as the If the filesystem you are implementing maps paths to the native filesystem, be sure to implement :py:meth:`~fs.base.FS.getsyspath`. Doing so will improve performance, especially when copying / moving files between FS objects. +.. _essential-methods: + Essential Methods ----------------- @@ -25,6 +27,8 @@ The following methods are required for a minimal Filesystem interface: * :meth:`~fs.base.FS.getinfo` Return information about the path e.g. size, mtime +.. _non-essential-methods: + Non - Essential Methods ----------------------- @@ -46,10 +50,12 @@ The following methods have default implementations in :py:class:`fs.base.FS` and * :meth:`~fs.base.FS.move` Move a file to a new location * :meth:`~fs.base.FS.movedir` Recursively move a directory to a new location * :meth:`~fs.base.FS.opendir` Opens a directory and returns an FS object that represents it - * :meth:`~fs.base.FS.safeopen` Like :meth:`~fs.base.open` but returns a NullFile if the file could not be opened + * :meth:`~fs.base.FS.safeopen` Like :meth:`~fs.base.FS.open` but returns a :class:`~fs.base.NullFile` if the file could not be opened * :meth:`~fs.base.FS.settimes` Sets the accessed and modified times of a path +.. _utility-methods: + Utility Methods --------------- -- cgit v1.2.1