experimental api refresh (#248)

* experimental api refresh

* method name changes

* setfile -> writefile

* added system to issue deprecation warnings

* test for deprecations warnings

* fix deprecation test

* deprecation fix

* update docs with new method names

* fix deprecation warning test

* change default chunk size

* chunk size

* fix mypy comment

* Extra args to FS.upload

* docstrings

* example

* docstring

* Example in docstring

* Added interface page to docs

* version bump

Author: willmcgugan

CHANGELOG.md

@@ -5,6 +5,26 @@ 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/).
 
+## [2.2.0] - 2018-01-01
+
+A few methods have been renamed for greater clarity (but functionality remains the same).
+
+The old methods are now aliases and will continue to work, but will
+issue a deprecation warning via the `warnings` module.
+Please update your code accordingly.
+
+- `getbytes` -> `readbytes`
+- `getfile` -> `download`
+- `gettext` -> `readtext`
+- `setbytes` -> `writebytes`
+- `setbinfile` -> `upload`
+- `settext` -> `writetext`
+
+### Changed
+
+- Changed default chunk size in `copy_file_data` to 1MB
+- Added `chunk_size` and `options` to `FS.upload`
+
 ## [2.1.3] - 2018-12-24
 
 ### Fixed

docs/source/guide.rst

@@ -8,7 +8,7 @@ Why use PyFilesystem?
 
 If you are comfortable using the Python standard library, you may be wondering; *why learn another API for working with files?*
 
-The PyFilesystem API is generally simpler than the ``os`` and ``io`` modules -- there are fewer edge cases and less ways to shoot yourself in the foot. This may be reason alone to use it, but there are other compelling reasons you should use ``import fs`` for even straightforward filesystem code.
+The :ref:`interface` is generally simpler than the ``os`` and ``io`` modules -- there are fewer edge cases and less ways to shoot yourself in the foot. This may be reason alone to use it, but there are other compelling reasons you should use ``import fs`` for even straightforward filesystem code.
 
 The abstraction offered by FS objects means that you can write code that is agnostic to where your files are physically located. For instance, if you wrote a function that searches a directory for duplicates files, it will work unaltered with a directory on your hard-drive, or in a zip file, on an FTP server, on Amazon S3, etc.
 
@@ -90,13 +90,13 @@ FS objects have a :meth:`~fs.base.FS.close` methd which will perform any require
 You can call ``close`` explicitly once you are finished using a filesystem. For example::
 
     >>> home_fs = open_fs('osfs://~/')
-    >>> home_fs.settext('reminder.txt', 'buy coffee')
+    >>> home_fs.writetext('reminder.txt', 'buy coffee')
     >>> home_fs.close()
 
 If you use FS objects as a context manager, ``close`` will be called automatically. The following is equivalent to the previous example::
 
     >>> with open_fs('osfs://~/') as home_fs:
-    ...    home_fs.settext('reminder.txt', 'buy coffee')
+    ...    home_fs.writetext('reminder.txt', 'buy coffee')
 
 Using FS objects as a context manager is recommended as it will ensure every FS is closed.
 
@@ -158,7 +158,7 @@ The :class:`~fs.base.FS.makedir` and :class:`~fs.base.FS.makedirs` methods also
     >>> home_fs = open_fs('~/')
     >>> game_fs = home_fs.makedirs('projects/game')
     >>> game_fs.touch('__init__.py')
-    >>> game_fs.settext('README.md', "Tetris clone")
+    >>> game_fs.writetext('README.md', "Tetris clone")
     >>> game_fs.listdir('/')
     ['__init__.py', 'README.md']
 
@@ -176,9 +176,9 @@ You can open a file from a FS object with :meth:`~fs.base.FS.open`, which is ver
 
 In the case of a ``OSFS``, a standard file-like object will be returned. Other filesystems may return a different object supporting the same methods. For instance, :class:`~fs.memoryfs.MemoryFS` will return a ``io.BytesIO`` object.
 
-PyFilesystem also offers a number of shortcuts for common file related operations. For instance, :meth:`~fs.base.FS.getbytes` will return the file contents as a bytes, and :meth:`~fs.base.FS.gettext` will read unicode text. These methods is generally preferable to explicitly opening files, as the FS object may have an optimized implementation.
+PyFilesystem also offers a number of shortcuts for common file related operations. For instance, :meth:`~fs.base.FS.readbytes` will return the file contents as a bytes, and :meth:`~fs.base.FS.readtext` will read unicode text. These methods is generally preferable to explicitly opening files, as the FS object may have an optimized implementation.
 
-Other *shortcut* methods are :meth:`~fs.base.FS.setbin`, :meth:`~fs.base.FS.setbytes`, :meth:`~fs.base.FS.settext`.
+Other *shortcut* methods are :meth:`~fs.base.FS.download`, :meth:`~fs.base.FS.upload`, :meth:`~fs.base.FS.writebytes`, :meth:`~fs.base.FS.writetext`.
 
 Walking
 ~~~~~~~

docs/source/implementers.rst

@@ -90,14 +90,12 @@ In the general case, it is a good idea to look at how these methods are implemen
 * :meth:`~fs.base.FS.copydir`
 * :meth:`~fs.base.FS.create`
 * :meth:`~fs.base.FS.desc`
+* :meth:`~fs.base.FS.download`
 * :meth:`~fs.base.FS.exists`
 * :meth:`~fs.base.FS.filterdir`
-* :meth:`~fs.base.FS.getbytes`
-* :meth:`~fs.base.FS.getfile`
 * :meth:`~fs.base.FS.getmeta`
 * :meth:`~fs.base.FS.getsize`
 * :meth:`~fs.base.FS.getsyspath`
-* :meth:`~fs.base.FS.gettext`
 * :meth:`~fs.base.FS.gettype`
 * :meth:`~fs.base.FS.geturl`
 * :meth:`~fs.base.FS.hassyspath`
@@ -111,15 +109,17 @@ In the general case, it is a good idea to look at how these methods are implemen
 * :meth:`~fs.base.FS.movedir`
 * :meth:`~fs.base.FS.open`
 * :meth:`~fs.base.FS.opendir`
+* :meth:`~fs.base.FS.readbytes`
+* :meth:`~fs.base.FS.readtext`
 * :meth:`~fs.base.FS.removetree`
 * :meth:`~fs.base.FS.scandir`
-* :meth:`~fs.base.FS.setbin`
-* :meth:`~fs.base.FS.setbytes`
-* :meth:`~fs.base.FS.setfile`
-* :meth:`~fs.base.FS.settext`
 * :meth:`~fs.base.FS.settimes`
 * :meth:`~fs.base.FS.touch`
+* :meth:`~fs.base.FS.upload`
 * :meth:`~fs.base.FS.validatepath`
+* :meth:`~fs.base.FS.writebytes`
+* :meth:`~fs.base.FS.writefile`
+* :meth:`~fs.base.FS.writetext`
 
 .. _helper-methods:
 

docs/source/index.rst

@@ -13,6 +13,7 @@ Contents:
 
    introduction.rst
    guide.rst
+
    concepts.rst
    info.rst
    openers.rst
@@ -22,6 +23,7 @@ Contents:
    implementers.rst
    extension.rst
    external.rst
+   interface.rst
    reference.rst
 
 

docs/source/info.rst

@@ -17,7 +17,7 @@ Here's an example of retrieving file information::
 
     >>> from fs.osfs import OSFS
     >>> fs = OSFS('.')
-    >>> fs.settext('example.txt', 'Hello, World!')
+    >>> fs.writetext('example.txt', 'Hello, World!')
     >>> info = fs.getinfo('example.txt', namespaces=['details'])
     >>> info.name
     'example.txt'

docs/source/interface.rst

@@ -0,0 +1,56 @@
+.. _interface:
+
+PyFilesystem API
+----------------
+
+The following is a complete list of methods on PyFilesystem objects.
+
+* :meth:`~fs.base.FS.appendbytes` Append bytes to a file.
+* :meth:`~fs.base.FS.appendtext` Append text to a file.
+* :meth:`~fs.base.FS.check` Check if a filesystem is open or raise error.
+* :meth:`~fs.base.FS.close` Close the filesystem.
+* :meth:`~fs.base.FS.copy` Copy a file to another location.
+* :meth:`~fs.base.FS.copydir` Copy a directory to another location.
+* :meth:`~fs.base.FS.create` Create or truncate a file.
+* :meth:`~fs.base.FS.desc` Get a description of a resource.
+* :meth:`~fs.base.FS.download` Copy a file on the filesystem to a file-like object.
+* :meth:`~fs.base.FS.exists` Check if a path exists.
+* :meth:`~fs.base.FS.filterdir` Iterate resources, filtering by wildcard(s).
+* :meth:`~fs.base.FS.getbasic` Get basic info namespace for a resource.
+* :meth:`~fs.base.FS.getdetails` Get details info namespace for a resource.
+* :meth:`~fs.base.FS.getinfo` Get info regarding a file or directory.
+* :meth:`~fs.base.FS.getmeta` Get meta information for a resource.
+* :meth:`~fs.base.FS.getsize` Get the size of a file.
+* :meth:`~fs.base.FS.getsyspath` Get the system path of a resource, if one exists.
+* :meth:`~fs.base.FS.gettype` Get the type of a resource.
+* :meth:`~fs.base.FS.geturl` Get a URL to a resource, if one exists.
+* :meth:`~fs.base.FS.hassyspath` Check if a resource maps to the OS filesystem.
+* :meth:`~fs.base.FS.hasurl` Check if a resource has a URL.
+* :meth:`~fs.base.FS.isclosed` Check if the filesystem is closed.
+* :meth:`~fs.base.FS.isempty` Check if a directory is empty.
+* :meth:`~fs.base.FS.isfile` Check if path maps to a file.
+* :meth:`~fs.base.FS.listdir` Get a list of resources in a directory.
+* :meth:`~fs.base.FS.lock` Get a thread lock context manager.
+* :meth:`~fs.base.FS.makedir` Make a directory.
+* :meth:`~fs.base.FS.makedirs` Make a directory and intermediate directories.
+* :meth:`~fs.base.FS.match` Match one or more wildcard patterns against a path.
+* :meth:`~fs.base.FS.move` Move a file to another location.
+* :meth:`~fs.base.FS.movedir` Move a directory to another location.
+* :meth:`~fs.base.FS.open` Open a file on the filesystem.
+* :meth:`~fs.base.FS.openbin` Open a binary file.
+* :meth:`~fs.base.FS.opendir` Get a filesystem object for a directory.
+* :meth:`~fs.base.FS.readbytes` Read file as bytes.
+* :meth:`~fs.base.FS.readtext` Read file as text.
+* :meth:`~fs.base.FS.remove` Remove a file.
+* :meth:`~fs.base.FS.removedir` Remove a directory.
+* :meth:`~fs.base.FS.removetree` Recursively remove file and directories.
+* :meth:`~fs.base.FS.scandir` Scan files and directories.
+* :meth:`~fs.base.FS.setinfo` Set resource information.
+* :meth:`~fs.base.FS.settimes` Set modified times for a resource.
+* :meth:`~fs.base.FS.touch` Create a file or update times.
+* :meth:`~fs.base.FS.tree` Render a tree view of the filesystem.
+* :meth:`~fs.base.FS.upload` Copy a binary file to the filesystem.
+* :meth:`~fs.base.FS.validatepath` Check a path is valid and return normalized path.
+* :meth:`~fs.base.FS.writebytes` Write a file as bytes.
+* :meth:`~fs.base.FS.writefile` Write a file-like object to the filesystem.
+* :meth:`~fs.base.FS.writetext` Write a file as text.

fs/_version.py

@@ -1,3 +1,3 @@
 """Version, used in module and setup.py.
 """
-__version__ = "2.1.3"
+__version__ = "2.2.0"