strict mode and docs

CHANGELOG.md

@@ -4,6 +4,11 @@ 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/).
 
+## [0.1.5] - 2017-10-21
+
+### Added
+
+- Added 'strict' parameter to constrictor.
 
 ## [0.1.4] - 2017-10-15
 

Makefile

@@ -23,4 +23,4 @@ testall:
 .PHONY: docs
 docs:
 	cd docs && make html
-	python -c "import os, webbrowser; webbrowser.open('file://' + os.path.abspath('./docs/build/html/index.html'))"
+	python -c "import os, webbrowser; webbrowser.open('file://' + os.path.abspath('./docs/_build/html/index.html'))"

README.md

@@ -11,21 +11,17 @@ same way as any other supported filesystem.
 
 Open an S3FS by explicitly using the constructor:
 
- ```python
-  from s3_s3fs import s3FS
-  s3fs = S3FS('mybucket')
-  # to use an s3-compatible service
-  s3fs = S3FS('mybucket', endpoint_url='service.endpoint.url')
-  ```
-
-  Or with a FS URL:
-
-  ```python
+```python
+from s3_s3fs import s3FS
+s3fs = S3FS('mybucket')
+```
+
+Or with a FS URL:
+
+```python
   from fs import open_fs
   s3fs = open_fs('s3://mybucket')
-  # to use an s3-compatible service
-  s3fs = open_fs('s3://mybucket?endpoint_url=service.endpoint.url')
-  ```
+```
 
 ## Downloading Files
 

docs/conf.py

@@ -23,6 +23,12 @@
 
 import fs_s3fs
 
+import sphinx_rtd_theme
+
+html_theme = "sphinx_rtd_theme"
+
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -84,7 +90,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+#html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/index.rst

@@ -42,8 +42,11 @@ it explicitly::
     from fs_s3fs import S3FS
     s3fs = S3FS('mybucket')
 
-See :class:`~fs_s3fs.S3FS` for other arguments you may pass to the
-constructor.
+S3FS Constructor
+----------------
+
+.. autoclass:: fs_s3fs.S3FS
+    :members:
 
 
 Authentication

fs_s3fs/_s3fs.py

@@ -202,25 +202,22 @@ class S3FS(FS):
     `PyFilesystem <https://pyfilesystem.org>`_
 
     :param str bucket_name: The S3 bucket name.
-    :param str dir_path: The root directory within the S3 Bucker.
-        Defaults to "/""
-    :param str aws_access_key_id: The access key, or None to read the
-        key from standard configuration files.
-    :param str aws_secret_access_key: The secret key, or None to read
+    :param str dir_path: The root directory within the S3 Bucket.
+        Defaults to ``"/"``
+    :param str aws_access_key_id: The access key, or ``None`` to read
         the key from standard configuration files.
+    :param str aws_secret_access_key: The secret key, or ``None`` to
+        read the key from standard configuration files.
     :param str endpoint_url: Alternative endpoint url (``None`` to use
         default).
     :param str aws_session_token:
     :param str region: Optional S3 region.
     :param str delimiter: The delimiter to separate folders, defaults to
         a forward slash.
-    :param bool strict: Validate correctness of the destination path.
-        For example, throw exception FileExpected() when a directory
-        path is supplied to ``setbinfile()`` method. 
-        These validations are quite expensive and normally can be 
-        safely disabled, assuming the client application doesn't mess 
-        with file paths intentionally.
-        Defaults to ``True``.
+    :param bool strict: When ``True`` (default) S3FS will follow the
+        PyFilesystem specification exactly. Set to ``False`` to disable
+        validation of destination paths which may speed up uploads /
+        downloads.
 
     """
 
@@ -612,9 +609,10 @@ def setinfo(self, path, info):
 
     def getbytes(self, path):
         self.check()
-        info = self.getinfo(path)
-        if not info.is_file:
-            raise errors.FileExpected(path)
+        if self.strict:
+            info = self.getinfo(path)
+            if not info.is_file:
+                raise errors.FileExpected(path)
         _path = self.validatepath(path)
         _key = self._path_to_key(_path)
         bytes_file = io.BytesIO()

fs_s3fs/_version.py

@@ -1 +1 @@
-__version__ = "0.1.4"
+__version__ = "0.1.5a0"

fs_s3fs/opener.py

@@ -22,6 +22,7 @@ def open_fs(self, fs_url, parse_result, writeable, create, cwd):
             raise OpenerError(
                 "invalid bucket name in '{}'".format(fs_url)
             )
+        strict = parse_result.params.get('strict', 'y') == 'y'
         s3fs = S3FS(
             bucket_name,
             dir_path=dir_path or '/',