Symlinks (#64)

* symlink info

* test fix for Py3

* made certain namespaces required in info attributes

* target fix

* without scandir fix

* landscape fix

* docs

* info tests

* version bump

* added permissiondenied error

* unused vars

* test info.is_link

Author: willmcgugan

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## Unreleased
+
+### Added
+- Lstat info namespace
+- Link info namespace
+- FS.islink method
+- Info.is_link method
+
+
 ## [2.0.7] - 2017-08-06
 
 ### Fixes

docs/source/info.rst

@@ -109,8 +109,9 @@ Name             type                Description
 gid              int                 The group ID.
 group            str                 The group name.
 permissions      Permissions         An instance of
-                                     :class:`~fs.permissions.Permissions`, which
-                                     contains the permissions for the resource.
+                                     :class:`~fs.permissions.Permissions`,
+                                     which contains the permissions for the
+                                     resource.
 uid              int                 The user ID.
 user             str                 The user name of the owner.
 ================ =================== ==========================================
@@ -129,6 +130,30 @@ filesystems which map directly to the OS filesystem. Most other
 filesystems will not support this namespace.
 
 
+LStat Namespace
+~~~~~~~~~~~~~~~
+
+The ``lstat`` namespace contains information reported by a call to
+`os.lstat <https://docs.python.org/3.5/library/stat.html>`_. This
+namespace is supported by :class:`~fs.osfs.OSFS` and potentially other
+filesystems which map directly to the OS filesystem. Most other
+filesystems will not support this namespace.
+
+Link Namespace
+~~~~~~~~~~~~~~
+
+The ``link`` namespace contains information about a symlink.
+
+=================== ======= ============================================
+Name                type    Description
+------------------- ------- --------------------------------------------
+target              str     A path to the symlink target, or ``None`` if
+                            this path is not a symlink.
+                            Note, the meaning of this target is somewhat
+                            filesystem dependent, and may not be a valid
+                            path on the FS object.
+=================== ======= ============================================
+
 Other Namespaces
 ~~~~~~~~~~~~~~~~
 
@@ -145,6 +170,30 @@ with the :meth:`~fs.info.Info.get` method.
     filesystem does *not* support. Any unknown namespaces will be
     ignored.
 
+Missing Namespaces
+------------------
+
+Some attributes on the Info objects require that a given namespace be
+present. If you attempt to reference them without the namespace being
+present (because you didn't request it, or the filesystem doesn't
+support it) then a :class:`~fs.errors.MissingInfoNamespace` exception
+will be thrown. Here's how you might handle such exceptions::
+
+    try:
+        print('user is {}'.format(info.user))
+    except errors.MissingInfoNamespace:
+        # No 'access' namespace
+        pass
+
+If you prefer a *look before you leap* approach, you can use use the
+:meth:`~fs.info.Info.has_namespace` method. Here's an example::
+
+
+     if info.has_namespace('access'):
+         print('user is {}'.format(info.user))
+
+See :class:`~fs.info.Info` for details regarding info attributes.
+
 Raw Info
 --------
 

fs/_version.py

@@ -1 +1 @@
-__version__ = "2.0.7"
+__version__ = "2.0.8a1"

fs/base.py

@@ -117,7 +117,8 @@ def makedir(self, path, permissions=None, recreate=False):
         :param permissions: :class:`~fs.permissions.Permissions`
             instance.
         :type permissions: Permissions
-        :param bool recreate: Do not raise an error if the directory exists.
+        :param bool recreate: Do not raise an error if the directory
+            exists.
         :rtype: :class:`~fs.subfs.SubFS`
 
         :raises fs.errors.DirectoryExists: if the path already exists.
@@ -707,6 +708,17 @@ def isfile(self, path):
         except errors.ResourceNotFound:
             return False
 
+    def islink(self, path):
+        """
+        Check if a path is a symlink.
+
+        :param str path: A path on the filesystem.
+        :rtype: bool
+
+        """
+        self.getinfo(path)
+        return False
+
     def lock(self):
         """
         Get a context manager that *locks* the filesystem.
@@ -727,7 +739,7 @@ def lock(self):
         multiple filesystem methods. Individual methods are thread safe
         already, and don't need to be locked.
 
-        ..note ::
+        .. note::
             This only locks at the Python level. There is nothing to
             prevent other processes from modifying the filesystem
             outside of the filesystem instance.

fs/compress.py

@@ -171,10 +171,11 @@ def write_tar(src_fs,
             tar_info.mtime = mtime
 
             for tarattr, infoattr in tar_attr:
-                if getattr(info, infoattr) is not None:
-                    setattr(tar_info, tarattr, getattr(info, infoattr))
+                if getattr(info, infoattr, None) is not None:
+                    setattr(tar_info, tarattr, getattr(info, infoattr, None))
 
-            tar_info.mode = getattr(info.permissions, 'mode', 0o420)
+            if info.has_namespace('access'):
+                tar_info.mode = getattr(info.permissions, 'mode', 0o420)
 
             if info.is_dir:
                 tar_info.type = tarfile.DIRTYPE

fs/error_tools.py

@@ -19,6 +19,7 @@ class _ConvertOSErrors(object):
 
     FILE_ERRORS = {
         64: errors.RemoteConnectionError,  # ENONET
+        errno.EACCES: errors.PermissionDenied,
         errno.ENOENT: errors.ResourceNotFound,
         errno.EFAULT: errors.ResourceNotFound,
         errno.ESRCH: errors.ResourceNotFound,

fs/errors.py

@@ -30,6 +30,7 @@
     'InsufficientStorage',
     'InvalidCharsInPath',
     'InvalidPath',
+    'MissingInfoNamespace',
     'NoURL',
     'OperationFailed',
     'OperationTimeout',
@@ -45,6 +46,16 @@
 ]
 
 
+class MissingInfoNamespace(AttributeError):
+    """Raised when an expected namespace was missing."""
+
+    def __init__(self, namespace):
+        msg = "namespace '{}' is required for this attribute"
+        super(MissingInfoNamespace, self).__init__(
+            msg.format(namespace)
+        )
+
+
 @six.python_2_unicode_compatible
 class FSError(Exception):
     """Base exception class for the FS module."""

fs/info.py

@@ -4,9 +4,9 @@
 
 from copy import deepcopy
 
-from . import filesize
 from .path import join
 from .enums import ResourceType
+from .errors import MissingInfoNamespace
 from .permissions import Permissions
 from .time import epoch_to_datetime
 
@@ -59,10 +59,8 @@ def get(self, namespace, key, default=None):
         >>> info.get('access', 'permissions')
         ['u_r', 'u_w', '_wx']
 
-        :param namespace: A namespace identifier.
-        :type namespace: str
-        :param key: A key within the namespace.
-        :type key: str
+        :param str namespace: A namespace identifier.
+        :param str key: A key within the namespace.
         :param default: A default value to return if either the
             namespace or namespace + key is not found.
         """
@@ -71,6 +69,15 @@ def get(self, namespace, key, default=None):
         except KeyError:
             return default
 
+    def _require_namespace(self, namespace):
+        """
+        Raise a MissingInfoNamespace if the given namespace is not
+        present in the info.
+
+        """
+        if namespace not in self.raw:
+            raise MissingInfoNamespace(namespace)
+
     def is_writeable(self, namespace, key):
         """
         Check if a given key in a namespace is writable (with
@@ -146,6 +153,17 @@ def is_file(self):
         """
         return not self.get('basic', 'is_dir')
 
+    @property
+    def is_link(self):
+        """
+        Check if a resource is a symlink.
+
+        :rtype: bool
+
+        """
+        self._require_namespace('link')
+        return self.get('link', 'target') is not None
+
     @property
     def type(self):
         """
@@ -154,8 +172,11 @@ def type(self):
         Requires the ``"details"`` namespace.
 
         :type: :class:`~fs.ResourceType`
+        :raises ~fs.errors.MissingInfoNamespace: if the 'details'
+            namespace is not in the Info.
 
         """
+        self._require_namespace('details')
         return ResourceType(self.get('details', 'type', 0))
 
     @property
@@ -167,8 +188,11 @@ def accessed(self):
         Requires the ``"details"`` namespace.
 
         :rtype: datetime
+        :raises ~fs.errors.MissingInfoNamespace: if the 'details'
+            namespace is not in the Info.
 
         """
+        self._require_namespace('details')
         _time = self._make_datetime(
             self.get('details', 'accessed')
         )
@@ -183,8 +207,11 @@ def modified(self):
         Requires the ``"details"`` namespace.
 
         :rtype: datetime
+        :raises ~fs.errors.MissingInfoNamespace: if the 'details'
+            namespace is not in the Info.
 
         """
+        self._require_namespace('details')
         _time = self._make_datetime(
             self.get('details', 'modified')
         )
@@ -199,8 +226,11 @@ def created(self):
         Requires the ``"details"`` namespace.
 
         :rtype: datetime
+        :raises ~fs.errors.MissingInfoNamespace: if the 'details'
+            namespace is not in the Info.
 
         """
+        self._require_namespace('details')
         _time = self._make_datetime(
             self.get('details', 'created')
         )
@@ -215,8 +245,11 @@ def metadata_changed(self):
         Requires the ``"details"`` namespace.
 
         :rtype: datetime
+        :raises ~fs.errors.MissingInfoNamespace: if the 'details'
+            namespace is not in the Info.
 
         """
+        self._require_namespace('details')
         _time = self._make_datetime(
             self.get('details', 'metadata_changed')
         )
@@ -230,8 +263,11 @@ def permissions(self):
         Requires the ``"access"`` namespace.
 
         :rtype: :class:`fspermissions.Permissions`
+        :raises ~fs.errors.MissingInfoNamespace: if the 'ACCESS'
+            namespace is not in the Info.
 
         """
+        self._require_namespace('access')
         _perm_names = self.get('access', 'permissions')
         if _perm_names is None:
             return None
@@ -246,8 +282,11 @@ def size(self):
         Requires the ``"details"`` namespace.
 
         :rtype: int
+        :raises ~fs.errors.MissingInfoNamespace: if the 'details'
+            namespace is not in the Info.
 
         """
+        self._require_namespace('details')
         return self.get('details', 'size')
 
     @property
@@ -258,8 +297,11 @@ def user(self):
         Requires the ``"access"`` namespace.
 
         :rtype: str
+        :raises ~fs.errors.MissingInfoNamespace: if the 'access'
+            namespace is not in the Info.
 
         """
+        self._require_namespace('access')
         return self.get('access', 'user')
 
     @property
@@ -270,8 +312,11 @@ def uid(self):
         Requires the ``"access"`` namespace.
 
         :rtype: int
+        :raises ~fs.errors.MissingInfoNamespace: if the 'access'
+            namespace is not in the Info.
 
         """
+        self._require_namespace('access')
         return self.get('access', 'uid')
 
     @property
@@ -283,8 +328,11 @@ def group(self):
         Requires the ``"access"`` namespace.
 
         :rtype: str
+        :raises ~fs.errors.MissingInfoNamespace: if the 'access'
+            namespace is not in the Info.
 
         """
+        self._require_namespace('access')
         return self.get('access', 'group')
 
     @property
@@ -295,6 +343,25 @@ def gid(self):
         Requires the ``"access"`` namespace.
 
         :rtype: int
+        :raises ~fs.errors.MissingInfoNamespace: if the 'access'
+            namespace is not in the Info.
 
         """
+        self._require_namespace('access')
         return self.get('access', 'gid')
+
+    @property
+    def target(self):
+        """
+        Get the link target, if this is a symlink, or ``None`` if this
+        is not a symlink.
+
+        Requires the ``"link"`` namespace.
+
+        :rtype: bool
+        :raises ~fs.errors.MissingInfoNamespace: if the 'link'
+            namespace is not in the Info.
+
+        """
+        self._require_namespace('link')
+        return self.get('link', 'target')

fs/iotools.py

@@ -1,8 +1,6 @@
 from __future__ import print_function
 from __future__ import unicode_literals
 
-import six
-
 import io
 from io import SEEK_SET, SEEK_CUR
 

fs/memoryfs.py

@@ -178,7 +178,7 @@ def size(self):
 
     def get_entry(self, name, default=None):
         assert self.is_dir, 'must be a directory'
-        return self._dir.get(name)
+        return self._dir.get(name, default)
 
     def set_entry(self, name, dir_entry):
         self._dir[name] = dir_entry